Tracks a control while the user holds down the mouse button.

typedef ControlPartCode(* ControlUserPaneTrackingProcPtr) (
    ControlRef control, 
    Point startPt, 
    ControlActionUPP actionProc
);

You would declare your function like this if you were to name it MyControlUserPaneTrackingCallback:

ControlPartCode MyControlUserPaneTrackingCallback (
    ControlRef control, 
    Point startPt, 
    ControlActionUPP actionProc
);

control

A handle to the control in which the mouse-down event occurred.

startPt

The location of the cursor at the time the mouse button was first pressed, in local coordinates. Your application retrieves this point from the where field of the event structure.

actionProc

A pointer to an action function defining what action your application takes while the user holds down the mouse button. The value of the actionProc parameter can be a valid procPtr, NULL, or -1. A value of -1 indicates that the control should either perform auto tracking, or if it is incapable of doing so, do nothing (like NULL).

function result

The part code of the control part that was tracked. If tracking was unsuccessful, kControlNoPartCode is returned.0

DISCUSSION

The Control Manager defines the data type ControlUserPaneTrackingUPP to identify the universal procedure pointer for this application-defined function:

typedef UniversalProcPtr ControlUserPaneTrackingUPP;

You typically use the NewControlUserPaneTrackingingProc macro like this:

ControlUserPaneTrackingUPP myControlUserPaneTrackingUPP;

myControlUserPaneTrackingUPP = NewControlUserPaneTrackingProc(MyControlUserPaneTrackingCallback);

You typically use the CallControlUserPaneTrackingingProc macro like this:

CallControlUserPaneTrackingProc(myControlUserPaneTrackingUPP, control, startPt, actionProc);

Your MyControlUserPaneTrackingCallback function should track the control by repeatedly calling the action function specified in the actionProc parameter until the mouse button is released. When the mouse button is released, your function should return the part code of the control part that was tracked. This function is called only if you’ve set the kControlHandlesTracking feature bit on creation of the user pane control.

Once you have provided a user pane application-defined function, you can call the function SetControlData in order to associate your function with a control. User pane application-defined functions are identified to SetControlData by tag constants; for a description of the tag constants, see the “Control Manager Constants” section. For example, once you have created the function MyControlUserPaneTrackingCallback, pass kControlUserPaneTrackingProcTag in the tagName parameter of SetControlData.

VERSION NOTES

This function is available with Appearance Manager 1.0 and later.

AVAILABILITY

Supported in Carbon.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)